v1 Simple Graphics API for Python ============================== Preliminaries All coordinates are given in pixels. The origin is the bottom left of the window (i.e., that pixel is (0,0) and coords increase upwards and rightwards). Any coordinate passed into the library can be given either as two arguments or as a pair of arguments. In this context "pair" means "2-tuple or 2-list". Colours are opaque objects made by |make_colour|. The library defines some useful ones. One can add ??and subtract?? colours, and multiply them by numbers. Query: should we "truncate" on every arithmetic operation? Or whenever a colour object is used? The former will make the following fail: new_colour = (colour1 + colour2) / 2 The latter complicates everything we do that makes any use of colours. Colour objects have accessors called |red()| etc. There is no supported way of changing a colour object once it is made. Comments Providing everything in here may be painful. For instance, the ability to pass coordinates jointly or severally may hurt a bit. We should experiment and see what works and what doesn't. In some sense perhaps the mouse things and colour things should be separated off. I don't think there's any point in doing that for our purposes, but I'm open to persuasion. The classes for mouse buttons and colours should have nice friendly "repr"s. We could even make them rereadable without great pain. It's not clear to me what predefined colours we want. Clearly primaries, black and white. Possibly also the standard Windows colours with their usual names? (Does that conflict with wanting the primaries too?) Would it be better to provide, instead of |mouse_position()| and |mouse_buttons()|, a single |mouse_state()| returning an object with a "position" field as well as ones for the buttons? ------------------------------------------------------------------------------ begin_graphics() Prepare to do graphics You should call this function before you start doing anything involving graphics. It will create a window, and initialise POINT to the top left of the window. Optional arguments: width The number of pixels left to right. height The number of pixels top to bottom. background The background colour. ------------------------------------------------------------------------------ end_graphics() Finish doing graphics Closes the window and throws away any resources we can. We may well be able to get away without needing this. ------------------------------------------------------------------------------ clear_screen() Clear the window. Clears the window to its background colour, discarding all its contents. Optional arguments: background The background colour. ------------------------------------------------------------------------------ move(x,y) Change POINT This doesn't draw anything; it just changes POINT, the location at which the next graphics operation will happen. You may also pass a single argument, a pair of coordinates. ------------------------------------------------------------------------------ plot(x,y) Plot a single point Changes the colour of the single pixel at (x,y) to COLOUR, or (optionally) to any other colour. (x,y) is the new value of POINT. You may also pass a single argument, a pair of coordinates. Optional arguments: colour The colour to use. ------------------------------------------------------------------------------ draw(x,y) Draw a line from POINT Draws a line from POINT to (x,y) in COLOUR or (optionally) any other colour. (x,y) is the new value of POINT. You may also pass a single argument, a pair of coordinates. Optional arguments: colour The colour to use. ------------------------------------------------------------------------------ line(x0,y0,x1,y1) Draw a line anywhere Precisely equivalent to move(x0,y0) followed by draw(x1,y1). The |colour| optional argument, if given, is handed to |draw|. You may make either (x0,y0) or (x1,y1) a pair of coordinates. Optional arguments: colour The colour to use. ------------------------------------------------------------------------------ set_colour(c) Change COLOUR This doesn't draw anything; it just changes COLOUR, the colour in which objects will be drawn. It also returns the previous value of COLOUR. ------------------------------------------------------------------------------ make_colour(r,g,b) Make a colour Returns an RGB triple or whatever else we decide to use for colours. Instead of r,g,b you can use keyword arguments |red|, |green|, |blue|, defaulting to 0. All values should be between 0 (dark) and 1 (bright). ------------------------------------------------------------------------------ text(t) Write text Draws some text. If |t| contains newlines, the results are undefined and may be unfortunate. The bottom left corner of the text (exactly what this means may differ between implementations, alas) is at POINT; the text is drawn in colour COLOUR. Several optional arguments affect exactly how it looks. POINT is not changed. The |size| and |serifs| arguments are not remembered between one call and the next. Optional arguments: colour The colour to use. size The nominal size to use, in pixels. angle The ccw angle from horizontal, in degrees. serifs (Flag) Used to choose a font. ------------------------------------------------------------------------------ set_textsize(s) Set size of text Changes the default size used in subsequent |text| calls. The size is the nominal height in pixels. This function returns the old value. ------------------------------------------------------------------------------ set_textserifs(flag) Set style of text Changes whether subsequent text operations will use serifs. This function returns the old value. ------------------------------------------------------------------------------ circle(x,y,r) Draw a circle Draws a circle with centre (x,y) and radius r, in colour COLOUR. You may pass (x,y) as a single argument. If what you really want is a circular arc or sector, pass the |endpoints| argument. It should be a pair of angles, measured in degrees anticlockwise from the rightward horizontal; the arc will go anticlockwise from the first to the second. Alternatively, either endpoint may be a coordinate pair, in which case the corresponding endpoint will be the intersection of the circle with the line joining the centre to that point. (Got that?) After doing this, POINT is (x,y) if endpoints weren't given; or the position of the second endpoint if they were. Optional arguments: colour The colour to use. filled Whether or not to fill it in (default is not) endpoints Angles of endpoints -- see above. ------------------------------------------------------------------------------ box(x0,y0,x1,y1) Draw a box Draws a box with opposite corners at (x0,y0) and (x1,y1). You may pass either coordinate pair as a pair. After doing this, POINT is (x1,y1). Optional arguments: colour The colour to use. filled Whether or not to fill it in (default is not) ------------------------------------------------------------------------------ polygon(p) Draw a polygon Draws a polygon with vertices given by the sequence p. p may be either a list of coordinate pairs or a list of coordinates. The latter might be more efficient for Tk, but is deprecated. After doing this, POINT is the last vertex in the list if the polygon wasn't to be closed, and the first if it was. Optional arguments: colour The colour to use. closed (flag) Whether or not to join last to first. filled (flag) Whether or not to fill it. ------------------------------------------------------------------------------ position() Return POINT Returns the current value of POINT as a pair. ------------------------------------------------------------------------------ begin_mouse() Prepare for mouse use Sets up whatever is needed for |mouse_position()| etc to work. ------------------------------------------------------------------------------ end_mouse() Finish with the mouse Call this when you're finished using the mouse. We may well be able to get by without this. ------------------------------------------------------------------------------ mouse_position() Where's the mouse? Returns the position of the mouse within the window, or None if the mouse isn't in the window. ------------------------------------------------------------------------------ mouse_buttons() Returns state of buttons Returns an object with fields |left| and |right|, each being a flag. Actually there's a |middle| field too, for people with *real* computers. :-) ------------------------------------------------------------------------------ mouse_wait(how) Wait for button click Does nothing until a mouse button is pressed. Or, optionally, until something else is true about the mouse state. The argument |how| is optional, defaulting to "down". It can have the following values: "down" Wait until a mouse button is down. "up" Wait until no mouse button is down. "change" Wait until the mouse buttons change. "click" Wait until a button goes down then up. "move" Wait until the mouse has changed position. "any" Wait until anything at all has changed.